home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / amok_lha / amok24.lha / TurboFiles / TurboFiles.dok < prev    next >
Text File  |  1993-08-15  |  9KB  |  170 lines
  1. TurboFiles.dok
  2. ~~~~~~~~~~~~~~
  3. TurboFiles ist ein Ersatz für das FileSystem von AM-Soft.
  4. Ich habe die wichtigsten Prozeduren in Assembler übersetzt ( zu
  5. erkennen an der Vorsilbe Turbo im Prozedurnamen), so daß sich
  6. gegenüber  FileSysten eine deutliche Geschwindigkeitssteigerung ergibt.
  7. Dieses Modul beschleunigt das Lesen und Schreiben von Dateien.
  8. Wenn man von einer Datei die Daten in sehr kleinen Portionen liest 
  9. oder hineinschreibt, ist die Benutzung von Dos recht langsam.
  10. Deshalb verwendet TurboFiles (wie FileSystem) einen Puffer. Daher
  11. müssen die DOS-Funktionen nur selten aufgerufen werden.
  12. Ein weiterer Vorteil von TurboFiles ist, daß geöffnete Files im
  13. Falle eines Programmabruches automatisch vervollständigt und
  14. geschlossen werden.
  15.  
  16. Die Benutzung von TurboFiles ist der von FileSystem sehr ähnlich.
  17. Wer schon mit FileSystem gearbeitet hat, sollte deshalb mit
  18. TurboFiles keine Schwierigkeiten haben.
  19. Falls Sie FileSystem noch nicht kennen, sollten Sie es sich vielleicht
  20. als erstes einmal ansehen, da ich in diesem Text eventuell 
  21. unbewußt einige dort beschriebene Dinge vorraussetze.
  22.  
  23. Ich habe die einzelnen Prozeduren im Definitionsmodul (das Sie
  24. sich ausdrucken sollten) ausführlich beschrieben, daher werde ich mich
  25. im folgenden etwas kürzer fassen.
  26.  
  27. Lookup(VAR f:FilePtr;VAR name:ARRAY OF CHAR;bufferSize:CARDINAL;
  28.        mode:AccesMode):TurboResult;
  29.   Jede Datei wird mit einer strukturierten Variablen von Typ File
  30.   identifiziert. Lookup gibt einen Zeiger auf diese File-Variable
  31.   zurück. Dieser Zeiger wird dann für alle folgenden Dateioperationen
  32.   benutzt. Die komponenten der File-Variable dürfen nicht
  33.   verändert werden. Das einzige Feld, das Sie benutzen sollten,
  34.   ist file^.res . Dieses Feld gibt Auskumft über den Status der
  35.   Datei und hat normalerweise den Wert done.
  36.   Die Prozedur Lookup öffnet das File und initialisiert
  37.   den Puffer. Außer DeleteFile() und Code() dürfen auf eine Datei keinerlei
  38.   Operationen ausgeführt werden, bevor die Datei nicht erfolgreich
  39.   geöffnet worden ist. name ist der Name der zu öffnenden Datei,
  40.   bufferSize bestimmt die Grösse des benutzten Puffers. Um eine
  41.   optimale Puffergröße zu finden, kann man das Programm SpeedCheck
  42.   verwenden. Wenn man von der Datei im Durchschnitt n Bytes liest,
  43.   so sollte der Puffer in der Größenordnung von 50*n bis 200*n liegen.
  44.   mode kann die Werte ReadOnly, ReadWrite oder NewFile haben.
  45.   Ist mode=ReadWrite, so kann man in die Datei abwechselnd schreiben
  46.   oder aus ihr lesen. NewFile legt eine neue Datei an (oder löscht eine
  47.   bestehende Datei dieses Namens) in die man dann Schreiben und aus der
  48.   man auch lesen kann.
  49.   Ist mode=ReadOnly, so kann man aus der Datei nur lesen. Der Vorteil
  50.   dieses Modus ist, daß man die Datei nicht verändern kann und daß
  51.   deshalb gleichzeitig andere Programme lesend auf diese Datei zu-
  52.   greifen können. Konnte die Datei geöffnet werden, wird der Wert
  53.   done als Resultat zurückgegeben und f zeigt fortan auf eine Variable
  54.   von Typ File, welche für (fast) alle weiteren Operationen benötigt wird.
  55.   
  56. CloseFile(VAR f:FilePtr);
  57.   Schließt die Datei wieder und gibt den für den Puffer belegten
  58.   Speicherbereich wieder frei. f bekommt den Wert NIL. Obwohl alle
  59.   geöffneten Dateien bein beenden des Programmes automatisch geschlossen
  60.   werden, und deshalb das explizite Schliessen der Dateien überflüssig
  61.   erscheinen mag, empfehle ich doch, die Dateien zu schliessen, sobald
  62.   man sie nicht mehr benötigt, damit andere Programme wieder auf diese
  63.   ungestört zugreifen können.
  64.   
  65. DeleteFile(VAR fileName:ARRAY OF CHAR):BOOLEAN;
  66.   Diese Prozedur ruft nur Dos.Delete auf um eine Datei zu löschen.
  67.   Achtung: Die Datei, die gelöscht werden soll, darf NICHT geöffnet sein.
  68.   Konnte die Datei gelöscht werden, so wird als Resultat TRUE zurückgegeben.
  69.  
  70. ReadBytes(f:FilePtr;adr:ADDRESS;len:LONGINT;VAR actual:LONGINT);
  71.   Diese Prozedur versucht, aus der durch f spezifizierten Datei len
  72.   Bytes zu lesen und speichert diese an der Stelle adr ab.
  73.   actual gibt an, wie viele Bytes gelesen werden konnten. Normalerweise
  74.   wird actual=len sein. Trat aber ein Fehler auf, z.B. daß die aktuelle
  75.   Position weniger als len Bytes von Dateiende entfernt ist, so wird
  76.   actual kleiner als len sein. Gleichzeitig wird f^.res einen Wert
  77.   ungleich done haben.
  78.   Man kann also wahlweise f^.res oder actual abfragen, um festzustellen
  79.   ob alle Daten erfolgreich gelesen worden sind.
  80.   Wird f^.res von irgendeiner Prozedur auf einen Wert ungleich done
  81.   gesetzt, so werden alle folgenden Prozeduraufrufe (außer CloseFile)
  82.   ignoriert. Man kann also z.B. ReadBytes mehrmals hintereinander aufrufen
  83.   und erst nach dem letzten Aufruf f^.res abfragen. Hat f^.res den Wert done,
  84.   so waren alle vorhergehenden Prozeduraufrufe erfolgreich, andernfalls
  85.   ist irgendwann ein Fehler aufgetreten.
  86.   
  87.   Beispiel:Lesen einer Zahl x aus einer Datei:
  88.   
  89.   VAR x:REAL;
  90.       act:LONGINT;
  91.   ReadBytes(offenesFile,ADR(x),SIZE(x),act);
  92.   IF act=SIZE(x) (* f^.res=done*) THEN
  93.     WriteString('OK')
  94.   ELSIF f^.res=endOfFile THEN
  95.     WriteString('Dateiende erreicht!')
  96.   ELSE
  97.     WriteString('Irgendein Fehler')
  98.   END;
  99.  
  100. WriteBytes(f:FilePtr;adr:ADDRESS,len:LONGINT);
  101.   Diese Prozedur schreibt die Variable, die an der Adresse adr steht und
  102.   len Bytes groß ist in die Datei. Ist f^.res#done, so ist ein
  103.   Fehler aufgetreten: Entweder ist die Diskette voll oder defekt.
  104.   Ist die Diskette voll, so erscheint ein Requester "Disk full...".
  105.   Dann kann man, nachden man einige unwichtige Files auf der Diskette
  106.   gelöscht hat, RETRY anklicken und ungestört fortfahren. Andernfalls
  107.   ist ein Teil der Datei verloren.
  108.   
  109. GetPos(f:FilePtr):LONGINT;
  110.   Gibt die momentane Position in der Datei zurück oder -1 falls
  111.   f^.res einen Wert ungleich done hat.
  112.   
  113. SetPos(f:FilePtr;offset:LONGINT;mode:SetPosMode):BOOLEAN;
  114.   Mit SetPos kann man die aktuelle Position innerhalb der Datei
  115.   frei bestimmen. Offset bestimmt die neue Position.
  116.   Ist mode=beginning, so wird offSet vom Anfang der Datei aus gemessen,
  117.   ist mode=end, so vom Ende der Datei aus. Ist mode=current, so
  118.   wird die aktuelle Position um offset verschoben; dabei verschiebt
  119.   ein positiver Wert die Position zum Dateiende, ein negativer zum
  120.   Dateianfang. Wird versucht, eine Position ausserhalb der Datei-
  121.   grenzen anzuwählen, so wird f^.res auf seekError gesetzt und
  122.   FALSE zurückgegeben.
  123.   
  124. FileLength(f:FilePtr):LONGINT;
  125.   Gibt die Länge der Datei in Bytes (oder -1 , falls f^.res#done) zurück.
  126.   
  127. Search(f:FilePtr;VAR str:ARRAY OF BYTE;len:LONGINT):LONGINT;
  128.   Sucht in der Datei ab der momentanen Position nach str, wobei
  129.   nur die ersten len Bytes von str berücksichtigt werden.
  130.   Wird str gefunden, so wird die aktuelle Position auf diese Stelle
  131.   gesetzt und diese Position wird zurückgegeben. Wird str nicht
  132.   gefunden, so wird -1 zurückgegeben und f^.res hat einen Wert
  133.   ungleich done.
  134.   
  135. Code(fileName,codeWord:ARRAY OF CHAR;decode:BOOLEAN):BOOLEAN;
  136.   Diese Prozedur dient zum Codieren von beliebigen Files.
  137.   Die Datei fileName darf NICHT geöffnet sein. codeWord ist
  138.   ein beliebiger String, der alle Zeichen bis auf 0C enthalten
  139.   darf und nicht länger als 256 Zeichen sein sollte. decode
  140.   gibt an ob die Datei codiert oder decodiert werden soll.
  141.   Man kann jede beliebige Datei codieren. Danach ist sie solange
  142.   unlesbar und unbrauchbar, bis sie wieder mit dem gleichen
  143.   Codewort decodiert worden ist. Die codierte Datei hat die selbe
  144.   Größe und den selben Namen wie das Original, d.h. das
  145.   Original wird überschrieben!
  146.   
  147. Die Prozeduren TurboRead, TurboWrite, TurboSetPos, TurboGetPos
  148. und TurboFileLength sind in Assembler geschrieben und verhalten
  149. sich genauso wie die Modula-Äquivalente, nur daß sie schneller
  150. und kleiner sind und deshalb bevorzugt verwendet werden sollten.
  151.  
  152. Außerdem  existieren noch die Prozeduren ReadChar, WriteChar,
  153. ReadByteBlock und WriteByteBlock. Diese Prozeduren rufen nur
  154. TurboRead und TurboWrite auf. Die Benutzung dieser Prozeduren
  155. ist zwar in einigen Fällen bequem, durch den doppelten
  156. Prozeduraufruf aber etwas langsamer als die direkte Benutzung
  157. von TurboRead und TurboWrite.
  158.  
  159. Noch ein Hinweis: Wie schon gesagt, werden alle Prozeduraufrufe
  160. außer CloseFile ignoriert, wenn f^.res einen Wert ungleich done
  161. hat. In der Regel ist dann ein Fehler aufgetreten und man wird die
  162. Datei schliessen. In einigen Fällen kann es aber sinnvoll sein,
  163. die Datei weiter zu bearbeiten, beispielsweise wenn durch
  164. Search oder TurboRead das Dateiende erreicht worden ist.
  165. Man kann dann f^.res auf done zurücksetzen und versuchen
  166. die Datei weiter zu bearbeiten.
  167.  
  168.  
  169. Stefan Salewski, 17.7.89
  170.